## Getting Started
1. Create a [Replicate.com](https://replicate.com) account
2. Add your payment method (required for using the API)
3. Generate an API key from your Replicate account settings
4. Add the API key in your Bubble app's Plugins tab
5. Start using the Orpheus TTS actions in your workflows

## How to Use

### Basic Setup

1. In your Bubble workflow, add the 'Replicate - Orpheus Text-to-Speech' action
2. Provide the text you want to convert to speech
3. Select your preferred voice (Tara, Dan, Josh, Emma)
4. Adjust optional parameters if needed (temperature, top_p, etc.)
5. Choose between direct mode or webhook mode

### Direct Mode vs. Webhook Mode

**Direct Mode (no webhook URL):**
- Your workflow will pause until the audio generation completes
- Best for backend workflows due to potential timeouts (Bubble has a 30s timeout limit)
- Returns the audio URL directly

**Webhook Mode:**
- Provides a prediction_id immediately and continues the workflow
- The specified webhook URL will be called when generation completes
- Ideal for handling longer generations without timeouts

### Using the Get Prediction by ID Action

When using webhook mode, you'll receive a prediction_id immediately. You can use the new 'Replicate - Get Prediction by ID' action to check the status of your prediction:

1. Store the prediction_id returned from the Orpheus TTS action
2. Use the 'Replicate - Get Prediction by ID' action with this prediction_id
3. Check the returned status (processing, succeeded, failed)
4. If status is 'succeeded', use the returned audio_url

This is useful for:
- Implementing polling to check if a prediction is complete
- Retrieving audio URLs for predictions initiated with webhooks
- Checking the status of failed predictions

### Using Expressions for Emotions

Orpheus can generate emotional speech using special tags:

```
Hey there <chuckle>, this is really amazing <laugh>! I'm feeling a bit <sigh> tired today.
```

### Important Notes About Audio URLs

**Audio URL Expiration:**
- URLs from Replicate expire after approximately 1 hour
- For permanent storage, download the files to your own storage

**ReadableStream Response:**
- The plugin handles the ReadableStream format from Replicate's API
- This is normal behavior and is processed automatically

**Handling Special Characters:**
- The plugin properly handles quotes and special characters in responses
- If processing URLs in custom code, ensure proper character escaping

**If you need permanent storage:**
- Set up a backend workflow to download and store audio files
- Use AWS S3, Google Cloud Storage, or a similar service
- Or save directly to your Bubble database as a file

### Example Workflow

1. Create a new data type called 'Generated Audio'
2. Add fields: text, prediction_id, audio_url, user, etc.
3. Add an input field and button on your page
4. Create a workflow when the button is clicked:
  - Call the Orpheus TTS action with your text
  - Set a webhook URL if processing asynchronously
5. Create a backend workflow (API Endpoint) to serve as your webhook
6. In this webhook, update your 'Generated Audio' record with the returned audio URL
7. Display an audio player element connected to your 'Generated Audio' URL

### Need Help?

For issues or feature requests, contact [email protected]

Editor demo : https://bubble.io/page?id=vima-plugin-replicate&test_plugin=1742549253032x528368106669342700_current&tab=Design&name=replicate-orpheus&type=page